Configuring web.oauth2 for end-user based authentication

4.1 Configuring web.oauth2 for end-user based authentication

The MyID authentication web service is called web.oauth2; you must configure this web service to allow access to the API. For end-user based authentication, you do this by configuring the server for acquisition of an access token, secured either by PKCE or a client secret.

Note: Before you begin, you must decide on a client ID for your external system; for example, myid.myclient. This represents your application (for example, website) that intends to make calls to the MyID Core API.

4.1.1 Configuring the authentication service for PKCE

For single-page apps, which run entirely on the client PC, you must secure the request for authentication using PKCE. This ensures that only the caller of the authorization can use the authorization code to request an access token.

In a text editor, open the appsettings.Production.json file for the web service.

By default, this is:

C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file.

Edit the file to include the following:

Copy

{
    "Clients":  [
    {
        "ClientId":  "<my client ID>",
        "ClientName":  "<my client name",
        "AccessTokenLifetime":  <time>,
        "AllowedGrantTypes":  [
            "authorization_code"
        ],
        "RequireClientSecret":  false,
        "RequirePkce":  true,
        "AllowAccessTokensViaBrowser":  true,
        "RequireConsent":  false,
        "AllowedScopes":  [
            "myid.rest.basic"
        ],
        "RedirectUris":  [
            "<callback URL>"
        ]
    }
    ]
}

where:

<my client ID> – the client ID you decided on; for example:

myid.mysystem
<my client name> – an easily readable name for your client system; for example:

My Client System
<time> – the time (in seconds) that the client credential is valid. The default is 3600 – 1 hour.
<callback URL> – the URL of the web page on your system to which the authorization code will be returned.

For example:

Copy

{
    "Clients":  [
    {
        "ClientId":  "myid.myclient",
        "ClientName":  "My Client System",
        "AccessTokenLifetime":  3600,
        "AllowedGrantTypes":  [
            "authorization_code"
        ],
        "RequireClientSecret":  false,
        "RequirePkce":  true,
        "AllowAccessTokensViaBrowser":  true,
        "RequireConsent":  false,
        "AllowedScopes":  [
        "myid.rest.basic"
        ],
        "RedirectUris":  [
            "https://myserver/mysystem/callback.asp"
        ]
    }
    ]
}

If you already have an appsettings.Production.json file, back up the existing file, then incorporate the new client section above into the file.

Important: If you have clients in the appsettings.json file and the appsettings.Production.json file, make sure the production file does not overwrite the entries in the base file. In these settings files, entries in arrays are determined by their index; therefore if you have four existing entries in the appsettings.json file, you must include four blank array entries {}, in the appsettings.Production.json file before you include your new client details. Alternatively, you can include the entire Clients array in the appsettings.Production.json file.

Save the configuration file.
Recycle the web service app pool:
1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.
This ensures that the web service has picked up the changes to the configuration file.
Check that the web.oauth2 server is still operational by logging on to the MyID Operator Client.

Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

HTTP Error 500.30 - ANCM In-Process Start Failure

See section 7, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

You can now obtain an access token; see section 4.2, Obtaining an end-user based access token using PKCE.

4.1.2 Configuring the authentication service for a client secret

For stateful web sites, where for example the server uses cookies to map stateful sessions between the client and the web server, it is recommended to configure the authentication service to require a client secret; you do not have to use PKCE, but you can use it in addition to the client secret if you want.

Note: The following instructions assume that you are using a client secret without PKCE. If you want to use both a client secret and PKCE, you can set both the RequireClientSecret and RequirePkce options to true, and then combine the requests for an authentication code and access token from section 4.2, Obtaining an end-user based access token using PKCE and section 4.3, Obtaining an end-user based access token using a client secret.

Before you edit the configuration file, create a client secret; see section 3.2.1, Creating a shared secret.

In a text editor, open the appsettings.Production.json file for the web service.

By default, this is:

C:\Program Files\Intercede\MyID\web.oauth2\appsettings.Production.json

This file is the override configuration file for the appsettings.json file for the web service. If this file does not already exist, you must create it in the same folder as the appsettings.json file.

Edit the file to include the following:

Copy

{
    "Clients":[
        {
            "ClientId":"<my client ID>",
            "ClientName":"<my client name",
            "AccessTokenLifetime": <time>,
            "AllowedGrantTypes":[
                "authorization_code"
            ],
            "RequireClientSecret":true,
            "RequirePkce":false,
            "AllowAccessTokensViaBrowser":true,
            "RequireConsent":false,
            "ClientSecrets":[
                {
                    "Value":"<secret>"
                }
            ],
            "AllowedScopes":[
                "myid.rest.basic"
            ],
            "RedirectUris":[
                "<callback URL>"
            ]
        }
    ]
}

where:

<my client ID> – the client ID you decided on; for example:

myid.mysystem
<my client name> – an easily readable name for your client system; for example:

My Client System
<time> – the time (in seconds) that the client credential is valid. The default is 3600 – 1 hour.
<secret> – the Base64-encoded SHA-256 hash of the secret you created; for example:

kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk=
<callback URL> – the URL of the web page on your system to which the authorization code will be returned.

For example:

Copy

{
    "Clients":[
        {
            "ClientId":"myid.myclient",
            "ClientName":"My Client System",
            "AccessTokenLifetime":3600,
            "AllowedGrantTypes":[
                "authorization_code"
            ],
            "RequireClientSecret":true,
            "RequirePkce":false,
            "AllowAccessTokensViaBrowser":true,
            "RequireConsent":false,
            "ClientSecrets":[
                {
                    "Value":"kv31VP5z/oKS0QMMaIfZ2UrhmQOdgAPpXV/vaF1cymk="
                }
            ],
            "AllowedScopes":[
                "myid.rest.basic"
            ],
            "RedirectUris":[
                "https://myserver/mysystem/callback.asp"
            ]
        }
    ]
}

If you already have an appsettings.Production.json file, back up the existing file, then incorporate the new client section above into the file.

Save the configuration file.
Recycle the web service app pool:
1. On the MyID web server, in Internet Information Services (IIS) Manager, select Application Pools.
2. Right-click the myid.web.oauth2.pool application pool, then from the pop-up menu click Recycle.
This ensures that the web service has picked up the changes to the configuration file.
Check that the web.oauth2 server is still operational by logging on to the MyID Operator Client.

Application setting JSON files are sensitive to such issues as comma placement; if the format of the file is not correct, the web service cannot load the file and will not operate, which may result in an error similar to:

HTTP Error 500.30 - ANCM In-Process Start Failure

See section 7, Troubleshooting for information on resolving problems that cause HTTP Error 500.30.

You can now obtain an access token; see section 4.3, Obtaining an end-user based access token using a client secret.